Report file names in which "Unexpected Julia interpolation" occurred #2793

aaruni96 · 2025-10-29T14:46:50Z

Depends on #2792

aaruni96 · 2025-10-29T14:50:12Z

In my testing, when I introduce a deliberate error in Oscar's experimental/FTheoryTools/docs/src/literature.md, I get the output

ERROR:     Unexpected Julia interpolation in the Markdown. This probably means that you have an
    unbalanced or un-escaped $ in the text.

    To write the dollar sign, escape it with `\$`

    Navnode is currently set to Experimental/FTheoryTools/literature.md, with parent NavNode(nothing, "F-Theory Tools", NavNode(nothing, ...)), and we
    got given the value:

    `$` which is of type `Symbol`

asinghvi17 · 2025-10-29T14:55:08Z

Navnode is currently set to Experimental/FTheoryTools/literature.md,

could probably be better rephrased to

This is on the page Experimental/FTheoryTools/literature.md,

src/html/HTMLWriter.jl

src/latex/LaTeXWriter.jl

…tion problems in markdown

Rephrase to be not quite so informal Co-authored-by: Max Horn <[email protected]>

fingolfin · 2025-11-04T11:11:27Z

src/html/HTMLWriter.jl

+        This is on the page $(locrepr(dctx.navnode.page)), with parent $(dctx.navnode.parent), and we
+        were given the value:


@aaruni96 PR #2803 is now merged. Can you please resolve the conflicts in CHANGELOG.md and then try this:

Suggested change

This is on the page $(locrepr(dctx.navnode.page)), with parent $(dctx.navnode.parent), and we

were given the value:

This is in file $(locrepr(dctx)), and we were given the value:

The missing docs before src is to be expected, given that Oscar's docs/make.jl does this:

cd(joinpath(oscardir, "docs")) do ... makedocs(; ... end

and the file names/paths we print are relative to the current working directory.

I am not sure why Oscar does that, it would be nice if we could get rid of it, but that's for another day.

and then try this:

This doesn't work, complains about wrong data types. I tried monkey patching a few things hoping its a trivial error, but I couldn't make any headway (just more and different errors).

The error I get is

ERROR: FieldError: type Documenter.HTMLWriter.HTMLContext has no field `page`, available fields: `doc`, `settings`, `scripts`, `documenter_js`, `themeswap_js`, `warner_js`, `search_index`, `search_index_js`, `search_navnode`, `atexample_warnings` Stacktrace: [1] getproperty @ ./Base_compiler.jl:54 [inlined] [2] locrepr(dctx::Documenter.HTMLWriter.DCtx, lines::Nothing) @ Documenter.HTMLWriter ~/Programs/git/GitHub/Documenter.jl/src/html/HTMLWriter.jl:715 [3] locrepr(dctx::Documenter.HTMLWriter.DCtx) @ Documenter.HTMLWriter ~/Programs/git/GitHub/Documenter.jl/src/html/HTMLWriter.jl:713 [4] domify(dctx::Documenter.HTMLWriter.DCtx, ::MarkdownAST.Node{Nothing}, e::MarkdownAST.JuliaValue) @ Documenter.HTMLWriter ~/Programs/git/GitHub/Documenter.jl/src/html/HTMLWriter.jl:2446 [5] domify(dctx::Documenter.HTMLWriter.DCtx, node::MarkdownAST.Node{Nothing}) @ Documenter.HTMLWriter ~/Programs/git/GitHub/Documenter.jl/src/html/HTMLWriter.jl:1813 [6] #domify##2 @ ~/Programs/git/GitHub/Documenter.jl/src/html/HTMLWriter.jl:1816 [inlined] ...

Argh. Seems my previous PR did not have enough coverage to reveal that I messed up... Try applying this patch in addition:

diff --git a/src/html/HTMLWriter.jl b/src/html/HTMLWriter.jl index 6868a874c..2803165fd 100644 --- a/src/html/HTMLWriter.jl +++ b/src/html/HTMLWriter.jl @@ -710,9 +710,7 @@ struct DCtx end function Documenter.locrepr(dctx::DCtx, lines = nothing) - doc = dctx.ctx.doc - page = dctx.navnode.page - return Documenter.locrepr(dctx.ctx.doc, dctx.ctx.page, lines) + return Documenter.locrepr(dctx.ctx.doc, dctx.navnode.page, lines) end function SearchRecord(ctx::HTMLContext, navnode; fragment = "", title = nothing, category = "page", text = "")

Without trying it now, relying on my memory of attempting something like this during my "monkey patching", I expect this to not work because dctx.navnode.page is a string, but locrepr expects something of type ::Page.

No, my patch is patching the locrepr method I added earlier today. It had a merge conflict which I resolved incorrectly.

After applying your patch, I still get the error I predicted :

ERROR: FieldError: type String has no field `source`; String has no fields at all. Stacktrace: [1] getproperty @ ./Base_compiler.jl:54 [inlined] [2] locrepr(doc::Documenter.Document, page::String, lines::Nothing) @ Documenter ~/Programs/git/GitHub/Documenter.jl/src/utilities/utilities.jl:84 [3] locrepr(dctx::Documenter.HTMLWriter.DCtx, lines::Nothing) @ Documenter.HTMLWriter ~/Programs/git/GitHub/Documenter.jl/src/html/HTMLWriter.jl:713

The locrepr method in utilities.jl doesn't specify needing the second argument as a ::Page, but assumes it, and tries accessing the field source.

src/latex/LaTeXWriter.jl

fingolfin · 2025-11-04T16:33:45Z

I've applied the adjustments and fixed the errors. At least in local tests it works fine (it's a bit hard to tell exactly without #2804 merged, and without the dedicated tests this really deserves, but we'll get there)

aaruni96 · 2025-11-04T22:29:05Z

In my testing, I get

ERROR:     Unexpected Julia interpolation in the Markdown. This probably means that you have an
    unbalanced or un-escaped $ in the text.

    To write the dollar sign, escape it with `\$`

    This is in file src/Experimental/FTheoryTools/literature.md, and we were given the value:

    `$` which is of type `Symbol`

With your earlier comment,

The missing docs before src is to be expected

I think, this is ready to be merged.

fingolfin · 2025-11-05T09:39:21Z

Taking a step back and thinking about this again, I wonder: perhaps we should simply perform this check earlier. Namely when we ingest docstrings (at which point we have precise location information), we could run a quick check on what we got and look for this issue, and report it then. This way, not only do we get better location info, but also we don't have to implement this for every writer again.

Thoughts @mortenpi ?

(To be clear, I'd still want to merge this PR, as it is an improvement now)

Now is more in line with our other warnings

fingolfin

I resolved conflicts, adjusted to the new "warning tests", then used the opportunity to in fact further adjust those warning messages to be properly indented.

fingolfin mentioned this pull request Oct 29, 2025

Some warnings not making build fail #2751

Open

fingolfin reviewed Oct 29, 2025

View reviewed changes

src/html/HTMLWriter.jl Outdated Show resolved Hide resolved

fingolfin reviewed Oct 29, 2025

View reviewed changes

src/html/HTMLWriter.jl Outdated Show resolved Hide resolved

fingolfin reviewed Oct 29, 2025

View reviewed changes

src/latex/LaTeXWriter.jl Outdated Show resolved Hide resolved

fingolfin added the Status: Waiting for Author The issue or pull request needs some action by its author label Oct 31, 2025

fingolfin mentioned this pull request Nov 1, 2025

Hidden warnings / errors (?) due to @quietly #2798

Open

aaruni96 force-pushed the ak96/more-info-on-mdparser-problems branch 2 times, most recently from 640dffe to 34bfb79 Compare November 3, 2025 10:04

aaruni96 and others added 4 commits November 3, 2025 11:05

Add some potentially helpful file information to unexpected interpola…

d2028ec

…tion problems in markdown

Apply suggestions from code review

da43460

Rephrase to be not quite so informal Co-authored-by: Max Horn <[email protected]>

use locrepr

41fba66

Slightly better phrasing of what the reported location is

827e554

aaruni96 force-pushed the ak96/more-info-on-mdparser-problems branch from 34bfb79 to 827e554 Compare November 3, 2025 10:05

Update changelog

8462744

This was referenced Nov 3, 2025

Automation: remove 'Waiting for Author' label in more cases #2802

Merged

Add locrepr methods, improve path generation #2803

Merged

fingolfin reviewed Nov 4, 2025

View reviewed changes

src/latex/LaTeXWriter.jl Outdated Show resolved Hide resolved

fingolfin added 2 commits November 4, 2025 17:27

Merge branch 'master' into ak96/more-info-on-mdparser-problems

ee2a0cb

tweaks

8ee9045

github-actions bot added Status: Waiting for Review The issue or PR needs feedback by a Documenter team member and removed Status: Waiting for Author The issue or pull request needs some action by its author labels Nov 4, 2025

fingolfin mentioned this pull request Nov 7, 2025

Add test for 'Unexpected Julia interpolation' warnings #2818

Merged

fingolfin added 2 commits November 7, 2025 13:04

Merge branch 'master' into ak96/more-info-on-mdparser-problems

63eb11b

Adjust tests

b555eb1

Adjust warning indentation

216ba07

Now is more in line with our other warnings

fingolfin approved these changes Nov 7, 2025

View reviewed changes

fingolfin changed the title ~~Add more info to mdparser problems~~ Report file names in which "Unexpected Julia interpolation" occurred Nov 7, 2025

fingolfin enabled auto-merge (squash) November 7, 2025 12:11

fingolfin added 2 commits November 7, 2025 13:12

runic

e63295b

seems runic is not perfect

b48b0f8

fingolfin merged commit 445275f into JuliaDocs:master Nov 7, 2025
24 of 25 checks passed

fingolfin mentioned this pull request Nov 7, 2025

Check for use of "unbalanced or un-escaped \$ in the text" much earlier #2821

Open

		This is on the page $(locrepr(dctx.navnode.page)), with parent $(dctx.navnode.parent), and we
		were given the value:

	This is on the page $(locrepr(dctx.navnode.page)), with parent $(dctx.navnode.parent), and we
	were given the value:
	This is in file $(locrepr(dctx)), and we were given the value:

Report file names in which "Unexpected Julia interpolation" occurred #2793

Report file names in which "Unexpected Julia interpolation" occurred #2793

Uh oh!

Conversation

aaruni96 commented Oct 29, 2025

Uh oh!

aaruni96 commented Oct 29, 2025

Uh oh!

asinghvi17 commented Oct 29, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

fingolfin Nov 4, 2025

Choose a reason for hiding this comment

Uh oh!

fingolfin Nov 4, 2025

Choose a reason for hiding this comment

Uh oh!

aaruni96 Nov 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

fingolfin Nov 4, 2025

Choose a reason for hiding this comment

Uh oh!

aaruni96 Nov 4, 2025

Choose a reason for hiding this comment

Uh oh!

fingolfin Nov 4, 2025

Choose a reason for hiding this comment

Uh oh!

aaruni96 Nov 4, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

fingolfin commented Nov 4, 2025

Uh oh!

aaruni96 commented Nov 4, 2025

Uh oh!

fingolfin commented Nov 5, 2025

Uh oh!

fingolfin left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

aaruni96 Nov 4, 2025 •

edited

Loading